…olicy

Issue #553 (CORE-MIGRATION-LEDGER.md row 9's Wave 2 prerequisite,
blocking R-15/#445 implementation) requires two decisions that no
existing roadmap/ADR settles: where persisted project schema-version
authority lives, and an explicit unknown-field policy that can never
silently drop persisted user data.

Adds docs/native/PROJECT-CORE-COMPATIBILITY-CONTRACT.md as a proposal,
not yet admitted:

- Persisted schemaVersion belongs to the project document itself,
  distinct from app/IndexedDB/contract/R-15 versions already tracked
  elsewhere in this codebase.
- First production version starts fresh at PROJECT_SCHEMA_V1 -- the
  existing Rust migrate.rs V1ToV2 proof and its revision_note field are
  explicitly harness-only (schema.rs's own doc comment says so) and are
  not canonicalized as real project history.
- Absent version classifies as LEGACY_UNVERSIONED, a distinct sentinel
  from PROJECT_SCHEMA_V1, never silently treated as current -- avoiding
  the exact synthesized-version risk issue #553 warns about.
- Future version fails closed (no write authority, no auto-migration,
  no auto-downgrade), mirroring the fail-closed philosophy migrate.rs
  already implements for its harness proof.
- Unknown-field policy is staged by field class rather than one global
  choice: not-yet-modeled persisted data (outline, binderNodes,
  compileProfile, projectGoals, writingHistory -- schema.rs's own
  StoryProject doc comment names these as out of scope today) gets
  OUT_OF_SCOPE_BUT_MUST_NOT_BE_DROPPED; additive fields on an
  already-Core-owned object get PRESERVE_OPAQUE; unknown values for
  closed semantic discriminants get REJECT_UNKNOWN; fully-owned fields
  get MODEL_AND_VALIDATE.
- Mechanism: a raw canonical payload as the lossless carrier, with a
  typed Core projection validating only currently-owned fields --
  evaluated per-struct rather than a blanket serde flatten/extra bucket
  across the whole object graph.
- Precise no-loss definition (semantic JSON equality, not
  byte-identical), a version-classification state machine, and
  authority-switch admission gates, none of which are satisfied yet.

CORE-MIGRATION-LEDGER.md row 9 updated to reference this proposal.

No code change. No authority switch. A maintainer decision record
(section 9) lists each decision for explicit confirmation before this
is treated as admitted; implementation is a separate, later PR.

…o-loss precision

Six corrections from review, each verified against live source before
fixing:

1. Version-classification overlap bug: the original state machine used
   a hardcoded "schemaVersion == 1" example inside SUPPORTED_OLDER,
   which is ambiguous with CURRENT at the very first release where
   version 1 is also current. Rewrote all classifications as strict
   comparisons against CURRENT_PROJECT_SCHEMA_VERSION, and added the
   missing UNSUPPORTED_OLDER/MIGRATION_GAP state (an older version with
   no registered migration path) as a genuinely distinct state from
   FUTURE, mirroring migrate.rs's existing MigrationError::NoMigrationFrom.

2. Field inventory was too narrow -- the most significant gap. Verified
   against live source: features/project/projectState.ts's ProjectData
   (the actual persisted/Redux shape) has ~20 fields, while types.ts's
   StoryProject interface (what coreEnvelope.ts operates on) has only
   11, and coreEnvelope.ts's buildCoreProjectEnvelope further narrows
   to 6 fields for the shadow envelope. Three narrowing steps exist,
   not the one the original draft described. Added §1.5 documenting
   this, §2.1.1 explicitly deciding that schemaVersion versions the
   full ProjectData surface (not StoryProject or the shadow-envelope
   projection), and a complete field-by-field inventory table covering
   every ProjectData field, not only the five schema.rs's own doc
   comment names.

3. The raw-carrier + typed-projection mechanism (§3.1) had no defined
   write-back invariant for editing a known field without destroying
   opaque sibling data. Added §3.2: known-field edits overlay onto the
   existing raw payload rather than re-serializing the typed projection
   as the whole document, with a source-generation revalidation before
   commit that fails closed on a stale merge target -- connects forward
   to future multi-writer/generation-authority work without
   implementing it here.

4. "Verbatim" preservation language contradicted the document's own
   semantic-equality (not byte-identical) no-loss definition. Replaced
   with precise semantic-preservation wording that explicitly allows
   whitespace/key-order/escape differences.

5. CORE-MIGRATION-LEDGER.md's row 9 update oversimplified the decision
   as a single "PRESERVE_OPAQUE unknown-field policy" when the actual
   proposal stages four distinct policies by field class. Corrected the
   wording.

6. Extended §9's maintainer decision record from 8 to 10 rows to cover
   the versioned-object decision (#2) and the write-back invariant
   (#9) as their own explicit, confirmable decisions rather than
   leaving them implicit under other rows.

No code change. No authority switch. Still awaiting maintainer sign-off
per §9 before this is treated as admitted.

…8 fix

Five corrections from a further review pass:

1. LEGACY_UNVERSIONED was described as dispatching into
   PROJECT_SCHEMA_V1's migration-registry entry for convenience, which
   -- since v1 is also the initial current version -- implied no
   explicit step ever actually executes, silently relabeling a legacy
   record as current with no stamp written and no verification
   performed. Replaced with an explicit, distinct, registered
   LEGACY_TO_V1 migration step (recognize legacy shape -> verify
   conformance to the v1 field inventory -> write schemaVersion: 1 for
   the first time -> no-loss verify -> durable commit).

2. Added a new required invariant, pre-contract downgrade safety
   (Sec 2.7): once a project is migrated to the schema-aware canonical
   form, a still-installed pre-contract build mutating its own
   untouched legacy-shaped copy must never have that mutation silently
   supersede the already-migrated record. The exact storage mechanism
   is left to the implementation PR (matching how Sec 2.1 already
   leaves the envelope representation unspecified), but the invariant
   itself is fixed here since it's a real product-format decision, not
   an implementation detail. Added as authority-switch gate 8 and
   Sec 9 decision row 12.

3. Fixed a markdown MD018 violation: a paragraph line-wrapped such
   that "#553" started a bare physical line, which markdownlint-cli2
   parses as an ambiguous ATX heading attempt. Wrapped issue/PR number
   references in backticks throughout so no line can start with a bare
   #NNN regardless of future rewrapping.

4. Resolved the Sec 5 gate-status self-contradiction CodeRabbit flagged
   (claiming "none are satisfied" while gate 7 said "already satisfied
   structurally"): reworded to distinguish "has structural evidence
   today" from "verified sufficient for an actual switch" -- only the
   latter closes any gate.

5. Made TS/Rust accept/reject parity (gate 4) a permanent, ongoing
   requirement rather than one scoped to "any transition window" --
   the React/PWA product and any native Core/Qt consumer are both
   permanent, coexisting implementations of the same format, not a
   temporary migration pair.

Also added a full fixture-class checklist (Sec 6.2) so gate 3's
"every fixture class" is no longer a dangling reference -- the
previous commit introduced this reference before the list existed to
back it.

No code change. No authority switch. Still awaiting maintainer
sign-off per Sec 9 before this is treated as admitted.

…w version parse

Four corrections from a further review pass, each verified before
fixing:

1. The MALFORMED classification claimed "existing preserve-first
   recovery UX, unchanged" -- verified false against live source:
   index.tsx's hydration path calls normalizePersistedProjectForStore,
   and on a falsy result it deletes the project key from
   preloadedState entirely, letting the app boot a blank project whose
   autosave can subsequently overwrite the original malformed record.
   This is destructive, not preserve-first. Corrected the claim and
   added it as authority-switch gate 9 / decision row 13: the web/IDB
   path must be brought to the same non-editable blocking recovery
   already required for FUTURE/MIGRATION_GAP, not assumed already
   correct.

2. Version classification implicitly assumed a full typed-schema parse
   happens before classification, but a FUTURE document making a
   breaking schema change (a plausible way for a real future version
   to differ) would fail that parse before its version is ever
   compared, misclassifying FUTURE as MALFORMED and denying it the
   correct newer-build recovery path. Added an explicit requirement:
   classification reads schemaVersion via a minimal raw/header parse
   first, full typed parsing only afterward.

3. The write-back merge invariant (Sec 3.2) verified only that unowned
   (opaque) paths survived unchanged -- an overlay bug that omitted an
   edit or wrote it to the wrong path would still pass that check and
   silently commit the wrong value. Added a second, owned-path
   verification: re-project the merged payload and confirm every owned
   path equals the intended edit before committing.

4. The same invariant's generation revalidation and the durable commit
   were described as two sequential steps, leaving a window for
   another writer to commit between them -- exactly the race the check
   exists to prevent. Specified that validation and commit must be one
   atomic, fenced operation (compare-and-swap or an exclusive lease
   spanning both), not a check-then-act pair.

Extended Sec 6.2's fixture list and Sec 9's decision record (rows
13-16) to cover all four. No code change. No authority switch. Still
awaiting maintainer sign-off per Sec 9 before this is treated as
admitted.

…D, bump policy

Closes the contract boundary per explicit maintainer scoping -- four
contract-level invariants only, no further open-ended review cascade,
no runtime implementation.

1. Universal ingress admission (Sec 2.8, contract invariant, admitted
   now): classification and schema admission must run on every ingress
   capable of producing editable project state, not only the primary
   load path -- naming stored-project load, filesystem load, IDB load,
   file/backup import, snapshot restore, recovery restore, and future
   native/Qt open as examples. Concrete per-path code changes are
   IMPLEMENTATION_REQUIRED, not designed here.

2. Identity-bearing collection merge (Sec 3.2, contract invariant,
   admitted now): characters, worlds, and equivalents merge by stable
   entity ID during the write-back overlay, never by array index or
   object-enumeration position; opaque sibling fields stay attached to
   the correct entity identity. Concrete merge implementation is
   IMPLEMENTATION_REQUIRED.

3. Schema version-bump policy (Sec 2.9, design decision, admitted
   now): required-field additions, removals/renames, type changes,
   incompatible semantic/invariant changes, non-additive
   closed-discriminant changes, and identity/order semantic changes
   all require a bump; a purely additive optional field routed through
   the staged unknown-field policy does not. This classification is a
   permanent release invariant, evaluated for every future format
   change.

4. Fixture-gate scoping correction (Sec 5 gate 3, Sec 6.2): split
   fixtures into admitted/migrated (semantic no-loss round-trip
   applies) and refused -- FUTURE, MIGRATION_GAP, MALFORMED (source
   preserved unchanged, zero durable writes, zero editable-state
   admission; never a round-trip proof, since nothing about a refused
   input is meant to be admitted or transformed).

Extended Sec 9 with rows 17-19 for the three new decisions, plus an
explicit IMPLEMENTATION_REQUIRED status block distinguishing every
concrete mechanic this document names from what it actually
implements (nothing -- this remains a proposal).

No code change. No authority switch. Awaiting maintainer sign-off per
Sec 9. This closes the proposal-development loop; further findings
belong to the implementation PR's own review, not another round here.

…contract

Six chatgpt-codex-connector findings landed on the already-signed-off head,
each verified against live source or the binding native roadmap before being
addressed: a cross-process-unsafe example in the write-back fence mechanism;
TS/Rust parity scoped to accept/reject only, missing migration-output
equality; the no-loss definition not accounting for the already-admitted
field-removal/rename bump case; the Group B refusal blanket not accounting
for the concurrent-write fixture starting from an already-admitted project;
no egress counterpart to universal ingress admission (verified against
useSettingsView.ts, BackupQuickActionsCard.tsx, libraryBackupService.ts, all
of which serialize a narrowed typed projection rather than the canonical raw
payload); and migration backup retention scoped only to "until commit," short
of ROADMAP-QT-GPUI-DESKTOP.md section 20's "backup before destructive
migration" rule.

None of these required a new product/security/legal decision or contradicted
any of the 19 maintainer-approved decision rows; each closes a loophole in an
already-admitted invariant and is recorded inline at its section.

Five findings landed on the admission commit itself (CodeRabbit x3,
chatgpt-codex-connector x2), each verified before being addressed: stale
proposal-stage confirm/amend/reject wording left in section 9's intro after
admission; the field inventory not stating that schemaVersion itself is
deliberately excluded from that table; the version classification not
defining accepted-value grammar for a present-but-invalid schemaVersion;
a verified gap where the filesystem backend (projectFsStore.ts,
legacyProjectIdentity.ts) persists two backend-specific fields absent from
ProjectData's declared type; and an explicit scope boundary against
ADR-0008's accepted-but-not-yet-flipped local-first Y.Doc authority model,
which this document does not extend to.

None required a new product/security/legal decision or contradicted any of
the 19 maintainer-approved decision rows.

…e loop

Six findings landed on the second-wave commit, each verified before being
addressed: the filesystem-metadata inventory row implied ordinary opaque
preservation across portable boundaries for local machine-trust data that
actually drives asset routing/quarantine decisions (corrected to require
stripping/re-derivation at portable boundaries); the additive-closed-enum
bump exemption contradicted REJECT_UNKNOWN's fail-closed intent (removed);
MODEL_AND_VALIDATE's "already validated" claim did not hold for a verified
field (wordCount) with a real TS/Rust domain mismatch (added a
never-invalidate-existing-data requirement); the no-loss definition did not
address JS/Rust large-integer precision divergence (added a lossless-numeric
requirement); the migration rename exemption did not require verifying a
renamed value landed at its destination (added); and the egress requirement
omitted snapshot creation as a distinct fourth call site (added).

None required a new product/security/legal decision or contradicted any of
the 19 maintainer-approved decision rows. This document is now explicitly
closed to further design-cascade rounds per its own new closing note: any
further finding is dispositioned in its review thread, not absorbed as
another revision.

… 3 gaps

The wave-two accepted-value-grammar text wrongly classified an absent
schemaVersion as MALFORMED, directly contradicting decision row 4
(LEGACY_UNVERSIONED, never MALFORMED, for an absent version) - a genuine bug
in this document's own prior text, not a refinement. Fixed, along with
making duplicate-schemaVersion-key rejection deterministic rather than
parser-dependent (was breaking permanent TS/Rust parity).

Two further real gaps, fixed alongside it: the write-back overlay invariant
read as scoped to a future Core writer only, when TypeScript is the actual
permanent writer it must also bind; and ordinary entity insertion/deletion
had no exception from "no invented/missing fields," making normal
add/delete character actions impossible to satisfy alongside the write-back
invariant.

This document is now explicitly closed to further design-cascade rounds -
a further finding is fixed only if it is a genuine self-contradiction with
an admitted row, otherwise dispositioned in its review thread without
another revision.